Skip to main content

Specification Writing

Learning Objectives​

By the end of this lesson, you will be able to:

  • Explain why a clear written specification is essential for protocol design.
  • Identify the core sections of a protocol or system specification (e.g., scope, behavior, constraints, diagrams).
  • Write simple, testable “shall”‑style requirements without vague language.
  • Use diagrams (state machines, data‑flow sketches) to complement text in your spec.

Introduction​

You already know how to:

  • distinguish protocol vs application,
  • model behavior with state machines, and
  • structure communication patterns.

Now it is time to document those ideas in a way that:

  • other engineers can understand,
  • stakeholders can review, and
  • the future‑you can read without guessing.

A specification (often called a “spec”) is a written description of what a system or protocol must do, not just what it might do [web:389][web:394].

In Flow‑style work, good specs help you:

  • align teams,
  • avoid mis‑implementations, and
  • keep protocols reusable and maintainable.

What Is a Specification?​

A specification is a document that describes:

  • what a system or protocol should do,
  • how it behaves in key scenarios, and
  • what constraints it must satisfy (e.g., performance, safety, security).

For protocols, a spec usually answers:

  • Who are the actors (clients, servers, nodes, voters, etc.)?
  • What messages can they exchange?
  • What state can the system be in?
  • What invariants or guarantees hold (e.g., “no double‑spend”)?

A good spec is:

  • clear: written in simple, precise language.
  • complete enough: enough to build from, but not overly detailed.
  • testable: each requirement can, at least in principle, be checked or tested.

This is the “paper‑design” stage before you drop into code.

Why Specs Matter for Protocols​

Protocols are often shared across many implementations and teams.
Without a written spec:

  • everyone has a slightly different mental model.
  • small differences in interpretation lead to interoperability bugs.

For example:

  • the IETF and similar standards bodies insist on detailed protocol specs because they expect many independent implementations to talk to each other [web:389][web:392].

In Flow‑style thinking:

  • writing a spec is an engineering discipline, not “extra documentation.”
  • it reduces churn, mis‑alignment, and re‑design later.

Core Sections of a Protocol Spec​

You do not need every section to be huge; just make sure each one is present and clear.

1. Title, Metadata, and Scope​

  • Title and short description of the protocol.
  • Authors / maintainers and contact.
  • Audience: who is this spec for? (engineers, PMs, governance bodies?)
  • Scope: what is in‑scope and what is not‑scope.

The “scope” is especially important because it:

  • stops people from over‑designing the protocol,
  • and keeps the spec focused on the core behavior.

2. Terminology and Definitions​

  • Define special terms used in the protocol, even if they seem obvious.
  • Point to external standards when you rely on them (e.g., “we use the definitions from RFC 2119 for MUST, SHOULD, MAY” [web:387]).

This avoids confusion like:

  • Does “user” mean “learner” or “admin”?
  • What does “valid proposal” actually mean?

3. Actors and Roles​

Describe:

  • Who the actors are (e.g., learner, mentor, validator, dashboard, governance‑body).
  • What each role is allowed to do (e.g., “only governance‑body can approve a proposal”).

This is part of security and policy design, not just naming.

4. Behavior and State​

Here you combine:

  • State machine ideas (from 02‑state‑machines.md).
  • Key messages or events (from 03‑communication‑patterns.md).

Structure this section around:

  • Core states of the protocol (e.g., DRAFT, UNDER_REVIEW, APPROVED).
  • Transitions between states (e.g., when event approve arrives, move from UNDER_REVIEW to APPROVED).
  • Message formats (e.g., JSON‑style shapes for requests, events, or transactions).

You can write:

  • a state‑transition table,
  • or short scenarios (e.g., “happy‑path proposal flow” and “rejection flow”).

5. Requirements and Constraints​

Turn behavior into requirements.

A common pattern is to use “shall” language to make specs testable [web:391][web:399]:

  • “The system shall persist the proposal when it transitions from DRAFT to UNDER_REVIEW.”
  • “The system shall not allow a proposal in state EXECUTED to be moved back to UNDER_REVIEW.”

Other constraints you may include:

  • Performance: latency, throughput, or load bounds.
  • Security: e.g., “only authenticated users may submit proposals.”
  • Availability / durability: how the system behaves under failures or restarts.

6. Data Formats and APIs​

For protocol‑style systems, you often want to pin down:

  • Data formats (e.g., fields in a proposal, fields in a vote or reward).
  • APIs or message endpoints (e.g., HTTP‑style endpoints or event‑schema) [web:397].

Even if you are not writing an RFC‑style spec, sketching these as:

  • JSON‑style examples,
  • or pseudocode type‑signatures,

helps prevent ambiguity when others implement clients or services.

7. Examples and Diagrams​

  • Include example flows (e.g., “submit → review → approve → execute”).

  • Add diagrams:

    • a state‑machine diagram,
    • a simple data‑flow between actors.

Diagrams are not “nice‑to‑have”; they are part of the spec and often prevent misunderstandings faster than pages of text.

Good Writing Habits for Specs​

1. Be Precise, Not Vague​

Avoid:

  • “the system should handle proposals quickly”
  • “users might be able to approve proposals.”

Instead:

  • “The system shall persist the proposal within 2 seconds of receiving a valid submit request.”
  • “Only users with role governance_admin shall be allowed to send an approve event.”

Precision makes it possible to verify and test the spec.

2. Use “Shall”, “Must”, “Should”, and “May”​

Standards like RFC 2119 define:

  • MUST / SHALL = this is required.
  • SHOULD = strongly recommended but there can be rare exceptions.
  • MAY = optional.

You do not need to follow RFC 2119 exactly, but being consistent helps everyone know what is mandatory and what is optional [web:387][web:399].

3. Keep It Lean and Focused​

  • Do not try to document every implementation detail.

  • Focus on:

    • what the protocol must guarantee,
    • and what the implementer is allowed to choose (e.g., internal algorithms, serialization format).

This keeps the spec readable and maintainable.

How This Fits Into Flow‑Style Work​

In Flow‑style protocols you can:

  • Write a core spec for the protocol (e.g., governance‑state machine, reward‑calculation rules).

  • Write second‑level specs for:

    • specific applications (e.g., dashboard, CLI, API).
    • or for ML‑driven score layers that plug into the protocol.

This separation allows:

  • the protocol spec to stay stable,
  • while applications can evolve without changing the underlying rules.

Furthermore, a good spec:

  • makes it easier to add new actors (e.g., new governance‑tools) later.
  • and makes onboarding new engineers much faster.

Practical Exercises​

Exercise 1: Draft a Tiny Protocol Spec​

Pick a small Flow‑style workflow (e.g., a proposal flow, reward‑calculation, or on‑ramp):

  • Write a short spec that includes:

    • title, authors, and scope,
    • a list of actors and roles,
    • a small state‑machine description (states + transitions),
    • a few “shall”‑style requirements.

Do not aim for perfection; aim for clarity and testability.

Exercise 2: Add Examples and Diagrams​

Using the same workflow:

  • Add one example scenario (e.g., “happy‑path” and one “error‑path”).
  • Sketch a state‑machine diagram (boxes + arrows) and paste it into your lab repo.

This trains you to write and draw at the same time.

Exercise 3: Review and Refine​

Ask yourself:

  • Is anything still ambiguous?
  • Are there places where different implementers might disagree on behavior?

Revise the spec to remove ambiguity and see how much clearer it becomes.

Self‑Assessment​

Rate yourself from 1 to 5:

  • I can explain why a written specification is important for protocol design.
  • I can structure a spec with core sections (scope, actors, behavior, requirements, data, examples).
  • I can write simple “shall”‑style requirements that are testable.
  • I can see how diagrams and text fit together in a Flow‑style protocol spec.

Action item: write a short note in your lab repo describing one Flow‑style protocol you documented in a spec and how that changed how you think about the design.

Video​

Next Steps​

  • Read 02-formal-and-semi-formal-notation.md next to learn lightweight ways to add more rigor (e.g., simple state‑machine tables) to your specs.
  • Treat every new Flow‑style protocol as something that must have a spec, even if it is short.
  • Keep your specs living: update them as you learn and iterate, just like your codebase.

This lesson gives Flow Initiative trainees a beginner‑level understanding of specification writing in protocol engineering, focusing on clear structure (title, scope, behavior, requirements, data, and examples), precise “shall”‑style requirements, and how to use diagrams to complement text in Flow‑style protocol and governance‑style systems.